|
|
The Java programming language was developed by Sun Microsystems, and is documented in references listed in Appendix B of The VRML 2.0 Sourcebook.
When Java program scripts are used, the MIME type must be application/octet-stream, and the file name extension must be ".class". Java ".class" files contain platform-independent byte code compiled by a Java compiler from Java text files in ".java" files. For example, the following Script node references a Java byte-code file using the url field:
Script {
url "Example.class"
eventIn SFFloat set_fraction
eventOut SFFloat value_changed
}
A ".class" Java byte-code file must contain one class with the same name as the file, minus the ".class" file name extension. For VRML program scripts, the class must be a subclass of the Script class defined in the "vrml.node" package. Additional packages needed by the program script include the "vrml" and "vrml.field" packages. For example, the following Java text imports the needed VRML packages and begins a class "Example":
import vrml.*;
import vrml.field.*;
import vrml.node.*;
class Example extends Script {
. . .
}
The Java API (Application Programming Interface) provides features grouped into the following categories and discussed in the next few sections:
Each interface field, eventIn, and eventOut in a program script's Script node may be accessed by using methods of the Script class from which the program script is subclassed. The Script class extends the standard Java Object class.
The Script class provides the following methods. In these, and later listings, the Java data type for each method argument and return value is indicated in italics preceding the name of the argument or return value. The data type is for informational purposes only and is not typed in when calling the method in a program script.
Node value = create( String nodeType )
The create method creates a new node of the type selected by the nodeType argument value. An InvalidNodeTypeException is thrown if the node type is not valid.
String nodeType = getType( )
The getType method returns the node type of the node ("Script" unless overridden by a sub-class).
Browser browser = getBrowser( )
The getBrowser method returns an instance of the Browser class that provides access to the current VRML browser.
Field fieldRef = getField( String fieldName )
The getField method returns a Field class instance that references an interface field in the program script's Script node. The fieldName argument value specifies the name of the field for which a reference is to be returned. An InvalidFieldExeception is thrown if the field name is not valid.
Field eventInRef = getEventIn( String eventInName )
The getEventIn method returns a Field class instance that references an interface eventIn in the program script's Script node. The eventInName argument value specifies the name of the eventIn for which a reference is to be returned. An InvalidEventInExeception is thrown if the eventIn name is not valid.
Field eventOutRef = getEventOut( String eventOutName )
The getEventOut method returns a Field class instance that references an interface eventOut in the program script's Script node. The eventOutName argument value specifies the name of the eventOut for which a reference is to be returned. An InvalidEventOutExeception is thrown if the eventOut name is not valid.
Several additional methods are provided in the Script class that are meant to be overridden by the program script when it extends the Script class. These additional methods include initialize, shutdown, eventsProcessed, and processEvents. Each of these event delivery methods are discussed later in this document..
Most of the above methods return an instance of the Field class. Field class instances provide access to the interface fields, eventIns, and eventOuts of the program script's Script node. In typical use, the returned instance of the Field class is cast to one of the VRML data types discussed in the next section. For instance, the following Java text gets an instance of a Script node eventOut names "value_changed":
private SFFloat value_changed = (SFFloat) getEventOut( "value_changed" );
Reading from or writing to a Field instance for an interface field reads or writes the field's value.
Reading from a Field instance for an interface eventOut reads the last value sent using that eventOut.
Writing to a Field instance for an interface eventOut sends the written value as an event. The time stamp for the event depends upon the function executing, as discussed below. The event is sent upon completion of the currently executing function. Assignment to the same eventOut interface variable multiple times during one execution of the function only sends one event, and that event contains the last value assigned to the interface variable.
The Field class is the root class for a hierarchy of constant (read-only), and non-constant (read-write) classes for the VRML data types. Non-constant class names match those of the VRML data types (e.g., SFColor, MFFloat, etc.). Constant class names match those of the VRML data types, preceded with the word "Const" (e.g., ConstSFColor, ConstMFFloat, etc.).
Each of the data type classes are subclassed directly, or indirectly off of the Field class. The class hierarchy is as follows:
java.lang.Object
vrml.Field
vrml.Field.SFBool, SFColor, SFFloat, etc.
vrml.MField
vrml.field.MFColor, MFFloat, etc.
vrml.ConstField
vrml.field.ConstSFBool, ConstSFColor, etc.
vrml.field.ConstMField
vrml.field.ConstMFColor, ConstMFFloat, etc.
The Field class provides the following method:
Object obj = clone( )
The clone method copies the current class instance and returns the copy.
The MField class extends Field and provides the following additional methods:
int size = size( )
The size method returns the size of the class instance's value list.
clear( )
The clear method empties the class instance's value list.
delete( int index )
The delete method deletes a value from the instance's value list. The index argument's value selects the value to delete.
The ConstField class extends Field and provides no additional methods.
The ConstMField class extends ConstField and provides the following additional method:
int size = size( )
The size method returns the size of the class instance's value list.
Each data type constant class provides methods to read instance values, while non-constant classes also provide methods to write instance values. Method names, argument structures, and functionality are standardized across data type classes, as follows:
className( dataType values... )
All non-constant data type classes provide one or more constructor methods with the same name as the class and a list of initial values.
int size = getSize( )
All multi-value list data type classes (e.g., MFFloat, MFNode, etc.) provide getSize methods to get the number of values in the list.
dataType value = getValue( )
getValue( dataType valueList )
Most data type classes provide one or more getValue methods to get the values within an instance. Single-component data type classes (e.g., SFFloat, SFBool, etc.) return a value as the value of the method. Multi-value or multi-component data types (e.g., MFFloat, SFColor, etc.) return a value list in an argument to the getValue method.
dataType value = get1Value( int index )
get1Value( int index, dataType valueList )
get1Value( int index, dataType values... )
Multi-value list data type classes (e.g., MFFloat, MFVec3f, etc.) provide get1Value methods to get a single value from their list of values. The index argument selects the value to get. Single-component data type classes return the value as the value of the method. Multi-component data type classes return the value in an argument to the get1Value method.
dataType value = setValue( dataType values... )
setValue( constDataType values... )
setValue( dataType valueList )
Most non-constant data type classes provide one or more setValue methods to set the values within an instance. Single-value data type classes may also return the new value. Arguments to the setValue methods provide the values to use to set those within the instance.
set1Value( int index, dataType values... )
set1Value( int index, constDataType values... )
Most non-constant multi-value list data type classes (e.g., MFFloat, MFColor, etc.) provide set1Value methods to set a single value in their list of values. The index argument selects the value to set. Arguments to the setValue methods provide the values to use to set those within the instance.
addValue( dataType values... )
addValue( constDataType values... )
Most non-constant multi-value list data type classes (e.g., MFFloat, MFColor, etc.) provide addValue methods to add a single value in their list of values. Arguments to the addValue methods provide the values to add to the instance.
insertValue( int index, dataType values... )
insertValue( int index, constDataType values... )
Most non-constant multi-value list data type classes (e.g., MFFloat, MFColor, etc.) provide insertValue methods to insert a single value into their list of values. The index argument selects location at which to insert the values. Arguments to the insertValue methods provide the values to insert into the instance.
The following listings provide method declarations for each of the data type classes. Methods marked with a (C) are available in the constant version of a data type class. All listed methods are available in the non-constant version of the data type class.
|
Data Type Class |
Method Declarations |
|
SFBool and ConstSFBool |
SFBool( boolean value ) |
|
(C) boolean value = getValue( ) |
|
|
boolean setValue( boolean value ) |
|
|
setValue( ConstSFBool value ) |
|
|
setValue( SFBool value ) |
|
|
SFColor and ConstSFColor |
SFColor( float red, float green, float blue ) |
|
(C) getValue( float color[ ] ) |
|
|
(C) float redComponent = red( ) |
|
|
(C) float greenComponent = green( ) |
|
|
(C) float blueComponent = blue( ) |
|
|
setValue( float color[ ] ) |
|
|
setValue( float red, float green, float blue ) |
|
|
setValue( ConstSFColor color ) |
|
|
setValue( SFColor color ) |
|
|
SFFloat and ConstSFFloat |
SFFloat( float f ) |
|
(C) float value = getValue( ) |
|
|
setValue( float f ) |
|
|
setValue( ConstSFFloat value ) |
|
|
setValue( SFFloat value ) |
|
|
SFImage and ConstSFImage |
SFImage( int width, int height, int components, byte pixels[ ] ) |
|
(C) int imageWidth = width( ) |
|
|
(C) int imageHeight = height( ) |
|
|
(C) int imageComponents = components( ) |
|
|
(C) getPixels( byte pixels[ ] ) |
|
|
setValue( int width, int height, int components, byte pixels[ ] ) |
|
|
SFInt32 and ConstSFInt32 |
SFInt32( int value ) |
|
(C) int value = getValue( ) |
|
|
setValue( int value ) |
|
|
setValue( ConstSFInt32 value ) |
|
|
setValue( SFInt32 value ) |
|
|
SFNode and ConstSFNode |
SFNode( Node value ) |
|
(C) Node value = getValue( ) |
|
|
setValue( Node value ) |
|
|
setValue( ConstSFNode value ) |
|
|
setValue( SFNode value ) |
|
|
SFRotation and ConstSFRotation |
SFRotation( float axisX, float axisY, float axisZ, float rotation ) |
|
(C) getValue( float rotation[ ] ) |
|
|
setValue( float rotation[ ] ) |
|
|
setValue( float axisX, float axisY, float axisZ, float rotation ) |
|
|
setValue( ConstSFRotation rotation ) |
|
|
setValue( SFRotation rotation ) |
|
|
SFString and ConstSFString |
SFString( String value ) |
|
(C) String value = getValue( ) |
|
|
setValue( String value ) |
|
|
setValue( ConstSFString value ) |
|
|
setValue( SFString value ) |
|
|
SFTime and ConstSFTime |
SFTime( double time ) |
|
(C) double value = getValue( ) |
|
|
setValue( double time ) |
|
|
setValue( ConstSFTime time ) |
|
|
setValue( SFTime time ) |
|
|
SFVec2f and ConstSFVec2f |
SFVec2f( float x, float y ) |
|
(C) getValue( float vec2[ ] ) |
|
|
(C) float xComponent = x( ) |
|
|
(C) float yComponent = y( ) |
|
|
setValue( float vec[ ] ) |
|
|
setValue( float x, float y ) |
|
|
setValue( ConstSFVec2f vec ) |
|
|
setValue( SFVec2f vec ) |
|
|
SFVec3f and ConstSFVec3f |
SFVec3f( float x, float y, float z ) |
|
(C) getValue( float vec3[ ] ) |
|
|
(C) float xComponent = x( ) |
|
|
(C) float yComponent = y( ) |
|
|
(C) float zComponent = z( ) |
|
|
setValue( float vec[ ] ) |
|
|
setValue( float x, float y, float z ) |
|
|
setValue( ConstSFVec3f vec ) |
|
|
setValue( SFVec3f vec ) |
|
|
MFColor and ConstMFColor |
MFColor( float value[ ][ ] ) |
|
MFColor( float value[ ] ) |
|
|
(C) int size = getSize( ) |
|
|
(C) getValue( float colors[ ][ ] ) |
|
|
(C) getValue( float colors[ ] ) |
|
|
setValue( float colors[ ][ ] ) |
|
|
setValue( int size, float colors[ ] ) |
|
|
setValue( ConstMFColor colors ) |
|
|
(C) get1Value( int index, float color[ ] ) |
|
|
(C) get1Value( int index, SFColor color ) |
|
|
set1Value( int index, float red, float green, float blue ) |
|
|
set1Value( int index, ConstSFColor color ) |
|
|
set1Value( int index, SFColor color ) |
|
|
addValue( float red, float green, float blue ) |
|
|
addValue( ConstSFColor color ) |
|
|
addValue( SFColor color ) |
|
|
insertValue( int index, float red, float green, float blue ) |
|
|
insertValue( int index, ConstSFColor color ) |
|
|
insertValue( int index, SFColor color ) |
|
|
MFFloat and ConstMFFloat |
MFFloat( float value[ ] ) |
|
(C) int size = getSize( ) |
|
|
(C) getValue( float values[ ] ) |
|
|
setValue( float values[ ] ) |
|
|
setValue( int size, float values[ ] ) |
|
|
setValue( ConstMFFloat value ) |
|
|
(C) float value = get1Value( int index ) |
|
|
set1Value( int index, float value ) |
|
|
set1Value( int index, ConstSFFloat value ) |
|
|
set1Value( int index, SFFloat value ) |
|
|
addValue( float value ) |
|
|
addValue( ConstSFFloat value ) |
|
|
addValue( SFFloat value ) |
|
|
insertValue( int index, float value ) |
|
|
insertValue( int index, ConstSFFloat value ) |
|
|
insertValue( int index, SFFloat value ) |
|
|
MFInt32 and ConstMFInt32 |
MFInt32( int value[ ] ) |
|
(C) int size = getSize( ) |
|
|
(C) getValue( int values[ ] ) |
|
|
setValue( int values[ ] ) |
|
|
setValue( int size, int values[ ] ) |
|
|
setValue( ConstMFInt32 value ) |
|
|
(C) int value = get1Value( int index ) |
|
|
set1Value( int index, int value ) |
|
|
set1Value( int index, ConstSFInt32 value ) |
|
|
set1Value( int index, SFInt32 value ) |
|
|
addValue( int value ) |
|
|
addValue( ConstSFInt32 value ) |
|
|
addValue( SFInt32 value ) |
|
|
insertValue( int index, int value ) |
|
|
insertValue( int index, ConstSFInt32 value ) |
|
|
insertValue( int index, SFInt32 value ) |
|
|
MFNode and ConstMFNode |
MFNode( Node value[ ] ) |
|
(C) int size = getSize( ) |
|
|
(C) getValue( Node values[ ] ) |
|
|
setValue( Node values[ ] ) |
|
|
setValue( int size, Node values[ ] ) |
|
|
setValue( ConstMFNode value ) |
|
|
(C) Node value = get1Value( int index ) |
|
|
set1Value( int index, Node value ) |
|
|
set1Value( int index, ConstSFNode value ) |
|
|
set1Value( int index, SFNode value ) |
|
|
addValue( Node value ) |
|
|
addValue( ConstSFNode value ) |
|
|
addValue( SFNode value ) |
|
|
insertValue( int index, Node value ) |
|
|
insertValue( int index, ConstSFNode value ) |
|
|
insertValue( int index, SFNode value ) |
|
|
MFRotation and ConstMFRotation |
MFRotation( float rotations[ ][ ] ) |
|
MFRotation( float rotations[ ] ) |
|
|
(C) int size = getSize( ) |
|
|
(C) getValue( float rotations[ ] [ ] ) |
|
|
(C) getValue( float rotations[ ] ) |
|
|
setValue( float rotations[ ][ ] ) |
|
|
setValue( int size, float rotations[ ] ) |
|
|
setValue( ConstMFRotation rotation ) |
|
|
(C) get1Value( int index, float rotation[ ] ) |
|
|
(C) get1Value( int index, SFRotation rotation ) |
|
|
set1Value( int index, float ax, float ay, float az, float angle ) |
|
|
set1Value( int index, ConstSFRotation rotation ) |
|
|
set1Value( int index, SFRotation rotation ) |
|
|
addValue( float ax, float ay, float az, float angle ) |
|
|
addValue( ConstSFRotation rotation ) |
|
|
addValue( SFRotation rotation ) |
|
|
insertValue( int index, float ax, float ay, float az, float angle ) |
|
|
insertValue( int index, ConstSFRotation rotation ) |
|
|
insertValue( int index, SFRotation rotation ) |
|
|
MFString and ConstMFString |
MFString( String value[ ] ) |
|
(C) int size = getSize( ) |
|
|
(C) getValue( String values[ ] ) |
|
|
setValue( String values[ ] ) |
|
|
setValue( int size, String values[ ] ) |
|
|
setValue( ConstMFString value ) |
|
|
(C) String value = get1Value( int index ) |
|
|
set1Value( int index, String value ) |
|
|
set1Value( int index, ConstSFString value ) |
|
|
set1Value( int index, SFString value ) |
|
|
addValue( String value ) |
|
|
addValue( ConstSFString value ) |
|
|
addValue( SFString value ) |
|
|
insertValue( int index, String value ) |
|
|
insertValue( int index, ConstSFString value ) |
|
|
insertValue( int index, SFString value ) |
|
|
MFTime and ConstMFTime |
MFTime( double times[ ] ) |
|
(C) int size = getSize( ) |
|
|
(C) getValue( double times[ ] ) |
|
|
setValue( double times[ ] ) |
|
|
setValue( int size, double times[ ] ) |
|
|
setValue( ConstMFTime times ) |
|
|
(C) double value = get1Value( int index ) |
|
|
set1Value( int index, double time ) |
|
|
set1Value( int index, ConstSFTime time ) |
|
|
set1Value( int index, SFTime time ) |
|
|
addValue( double time ) |
|
|
addValue( ConstSFTime time ) |
|
|
addValue( SFTime time ) |
|
|
insertValue( int index, double time ) |
|
|
insertValue( int index, ConstSFTime time ) |
|
|
insertValue( int index, SFTime time ) |
|
|
MFVec2f and ConstMFVec2f |
MFVec2f( float vecs[ ][ ] ) |
|
MFVec2f( float vecs[ ] ) |
|
|
(C) int size = getSize( ) |
|
|
(C) getValue( float vecs[ ][ ] ) |
|
|
(C) getValue( float vecs[ ] ) |
|
|
setValue( float vecs[ ] ) |
|
|
setValue( int size, float vecs[ ] ) |
|
|
setValue( ConstMFVec2f vecs ) |
|
|
(C) get1Value( int index, float vec[ ] ) |
|
|
(C) get1Value( int index, SFVec2f vec ) |
|
|
set1Value( int index, float x, float y ) |
|
|
set1Value( int index, ConstSFVec2f vec ) |
|
|
set1Value( int index, SFVec2fvec ) |
|
|
addValue( float x, float y ) |
|
|
addValue( ConstSFVec2f vec ) |
|
|
addValue( SFVec2fvec ) |
|
|
insertValue( int index, float x, float y ) |
|
|
insertValue( int index, ConstSFVec2f vec ) |
|
|
insertValue( int index, SFVec2fvec vec ) |
|
|
MFVec3f and ConstMFVec3f |
MFVec3f( float vecs[ ][ ] ) |
|
MFVec3f( float vecs[ ] ) |
|
|
(C) int size = getSize( ) |
|
|
(C) getValue( float vecs[ ][ ] ) |
|
|
(C) getValue( float vecs[ ] ) |
|
|
setValue( float vecs[ ] ) |
|
|
setValue( int size, float vecs[ ] ) |
|
|
setValue( ConstMFVec3f vecs ) |
|
|
(C) get1Value( int index, float vec[ ] ) |
|
|
(C) get1Value( int index, SFVec3f vec ) |
|
|
set1Value( int index, float x, float y, float z) |
|
|
set1Value( int index, ConstSFVec3f vec ) |
|
|
set1Value( int index, SFVec3fvec ) |
|
|
addValue( float x, float y, float z) |
|
|
addValue( ConstSFVec3f vec ) |
|
|
addValue( SFVec3fvec ) |
|
|
insertValue( int index, float x, float y, float z ) |
|
|
insertValue( int index, ConstSFVec3f vec ) |
|
|
insertValue( int index, SFVec3fvec vec ) |
The Node class extends the standard Java Object class. An instance of the Node class is returned as the value of an SFNode or MFNode class instance. Node class methods provide access to a node's exposed fields, eventIns, and eventOuts. The following method's are included in the Node class.
Node value = create( String nodeType )
The create method creates a new node of the type selected by the nodeType argument value. An InvalidNodeTypeException is thrown if the node type is not valid.
String nodeType = getType( )
The getType method returns the node type of the node.
Browser browser = getBrowser( )
The getBrowser method returns an instance of the Browser class that provides access to the current VRML browser.
Field fieldRef = getExposedField( String fieldName )
The getExposedField method returns a Field class instance that references a field in the node. The fieldName argument value specifies the name of the field for which a reference is to be returned. An InvalidExposedFieldExeception is thrown if the field name is not valid.
Field eventInRef = getEventIn( String eventInName )
The getEventIn method returns a Field class instance that references an eventIn in the node. The eventInName argument value specifies the name of the eventIn for which a reference is to be returned. An InvalidEventInExeception is thrown if the eventIn name is not valid.
ConstField eventOutRef = getEventOut( String eventOutName )
The getEventOut method returns a Field class instance that references an eventOut in the node. The eventOutName argument value specifies the name of the eventOut for which a reference is to be returned. An InvalidEventOutExeception is thrown if the eventOut name is not valid.
The getExposedField, getEventIn, and getEventOut methods return an instance of the Field or ConstField classes. Field and ConstField class instances provide access to the fields, eventIns, and eventOuts of the node.
If the value of the program script's Script node directOutput field is FALSE:
No other read or write operations are allowed when the directOutput field value is FALSE.
Otherwise, when the directOutput field value is TRUE:
A Java program script creates a class that extends the Script class. Methods in the program script's class handle initialization, shutdown and event receipt. The Script class provides default methods that should be overridden in the program script. All overridden methods should be public void and match the prototypes below:
initialize( )
The initialize method is called when the program script is loaded and before delivery of any events to the program script. The initialize method is optional and may be omitted if there is no need for initialization actions. Events generated by the method are time stamped with the absolute time at which the program script was loaded.
shutdown( )
The shutdown method is called when the program script is about to be deleted. The shutdown method is optional and may be omitted if there is no need for shutdown actions. Events generated by the method are time stamped with the absolute time at which the program script's Script node was deleted.
eventInName( constDataType eventValue, ConstSFTime eventTime )
Each interface eventIn defined in the program script's Script node must have a corresponding method with the same name. The eventIn method is called when a new event is available for the node's eventIn. The value of the eventValue argument is the value of the incoming event. The constant data type of the eventValue argument corresponds to the VRML data type for the eventIn. The value of the eventTime argument is the time stamp of the incoming event. The time stamp holds the absolute time at which the event was created. Events generated by the method are time stamped with the absolute time value of the eventTime argument.
eventsProcessed( )
The eventsProcessed method is called upon completion of processing one or more pending events for the program script. Events generated by the method are time stamped with the absolute time value of the last event processed before calling the eventsProcessed method.
The default event dispatching mechanism delivers events to the eventIn methods of the class. The program script can override this default by providing a processEvents method.
processEvents( EventsIn events[ ] )
The processEvents method is called when there are events to be dispatched. The default method dispatches them to individual eventIn methods.
The processEvents method is passed a list of events, each an instance of the EventIn class. The EventIn class provides the following methods:
String name = getName( )
The getName method returns name of the event's value type.
SFTime time = getTimeStamp( )
The getTimeStamp method returns the time stamp for the event.
ConstField value = getValue( )
The getValue method returns the event value.
The getBrowser method of the Script and Node classes returns an instance of the Browser class. The Browser class provides methods for getting browser information, changing world content, and loading world content.
float frameRate = getCurrentFrameRate( )
The getCurrentFrameRate method returns the current drawing frame rate, measured in frames per second. If the frame rate cannot be determined, or the VRML browser does not support frame rate computation, a 0.0 is returned.
float moveSpeed = getCurrentSpeed( )
The getCurrentSpeed method returns the current movement speed of the viewer, measured in units per second. If the speed cannot be determined, is not meaningful for the current navigation type, or the VRML browser does not support movement speed computation, a 0.0 is returned.
String name = getName( )
The getName method returns the name of the VRML browser currently in use. The format of the browser name is browser-dependent. If the browser name cannot be determined, or the VRML browser does not support returning a browser name, an empty string is returned.
String url = getWorldURL( )
The getWorldURL method returns the URL for the currently loaded world. If the world includes inlined files, the returned URL is that of the top-most world from which everything else is inlined.
String version = getVersion( )
The getVersion method returns a version name for the VRML browser currently in use. The format of the version name is browser-dependent. If the browser name cannot be determined, or the VRML browser does not support returning a browser name, an empty string is returned.
addRoute( Node fromNode, String fromEventOut, Node toNode, String toEventIn )
The addRoute method creates a new route from the node indicated in the fromNode argument, to the node indicated in the toNode argument. The route connects the eventOut selected in the fromEventOut argument to the eventIn selected in the toEventIn argument. The InvalidRouteException is thrown if one of the argument values is invalid.
Node newWorld[ ] = createVrmlFromString(String vrmlSyntax )
The createVrmlFromString method creates a new world, or portion of a world, using the VRML syntax contained within the vrmlSyntax argument. The vrmlSyntax argument value may contain any node descriptions, exactly as they might occur in a VRML file. The returned list of node objects may be added to the current world, or used to replace the current world by using the replaceWorld method. The InvalidVRMLException is thrown if there is an error in the VRML syntax.
createVrmlFromUrl( String url[ ], Node receiverNode, String eventInName )
The createVrmlFromUrl method creates a new world, or portion of a world, by loading a VRML file using the list of URLs in the url argument. The value of the url argument specifies a prioritized list of URLs for a world to load, ordered from highest priority to lowest. The VRML browser starts by trying to open the world specified by the first URL in the list. If the world cannot be found, the browser tries the second URL in the list, and so on. When a URL is found that indicates a world that can be opened, the world is loaded into the browser. If none of the URLs can be opened, then no world is loaded and the browser may alert the viewer that an error has occurred. When the world, or part of a world, is loaded, an event is sent to a receiver node. The receiver node is indicated by the value of the receiverNode argument. The name of the eventIn method to be called is indicated by the value of the eventInName argument. When the receiver node's eventIn method is called, the event value is a list of node objects for the new world, or portion of a world. The event's list of node objects may be added to the current world, or used to replace the current world by using the replaceWorld method. The InvalidVRMLException is thrown if there is an error in the VRML syntax of the loaded file.
deleteRoute( Node fromNode, string fromEventOut, Node toNode, string toEventIn )
The deleteRoute method removes an existing route from the node indicated in the fromNode argument, to the node indicated in the toNode argument. The method disconnects the route from the eventOut selected in the fromEventOut argument to the eventIn selected in the toEventIn argument. The InvalidRouteException is thrown if one of the argument values is invalid.
setDescription( String description )
The setDescription method replaces the current text description of the world with the text in the description argument. Most browsers display the description in the window title bar for the browser.
loadURL( String url[ ], String parameters[ ] )
The loadURL method loads a world using the list of URLs in the url argument and the list of parameters in the parameters argument. Depending upon the parameters, the loaded world may replace the current world, causing all shapes in the current world to be deleted, and all current program scripts to be shut down. The value of the url argument specifies a prioritized list of URLs for a world to load, ordered from highest priority to lowest. The VRML browser starts by trying to open the world specified by the first URL in the list. If the world cannot be found, the browser tries the second URL in the list, and so on. When a URL is found that indicates a world that can be opened, the world is loaded into the browser. If none of the URLs can be opened, then no world is loaded and the browser may alert the viewer that an error has occurred. The value of the parameters argument specifies optional browser parameters that control how the new world is loaded. Parameters argument values are the same as discussed in Chapter XX for the Anchor node. In one use, the parameters argument value may select a target frame in the browser as the destination of the loaded world. If that target frame is the same as the frame containing the current world, then the current world is replaced by the new world. This method returns immediately. The InvalidVRMLException is thrown if there is an error in the VRML syntax of the loaded file.
loadWorld( String url [ ])
Similar to the loadURL method, the loadWorld method loads a world using the list of URLs in the url argument. The loaded world always replaces the current world, causing all shapes in the current world to be deleted, and all current program scripts to be shut down. The value of the url argument specifies a prioritized list of URLs for a world to load, ordered from highest priority to lowest. The VRML browser starts by trying to open the world specified by the first URL in the list. If the world cannot be found, the browser tries the second URL in the list, and so on. When a URL is found that indicates a world that can be opened, the world is loaded into the browser. If none of the URLs can be opened, then no world is loaded and the browser may alert the viewer that an error has occurred. This method may not return, since the world containing the calling program script is replaced by the new world loaded from the URL.
replaceWorld( Node newWorld[ ] )
The replaceWorld method replaces the current world with the list of nodes in the newWorld argument. All shapes in the current world are deleted, and all current program scripts are shut down. This method may not return, since the world containing the calling program script is replaced by the new world.